
                       Black Hole Miscellaneous Help
                       =============================
                       
This text explains the following:

1) What Black Hole does.
2) The functions of the menu features not covered elsewhere.

What does Black Hole do?
========================

[1]
Put very simply, Black Hole deletes files from discs. When you run it, a
little icon (a picture to you) will appear on the iconbar (the light grey
bit at the bottom of your screen). If you drag a file from a directory onto
this icon, the file will be deleted! Woopee!

It does a lot of other things too, but they'll only confuse you:

Like it has a file finder and a screen saver. And some other stuff.

[234]
Black Hole was written to provide quick and easy ways of doing some of the
more tedious jobs under RISC OS. It started life as a wastebin, but then
whenever I found a job I wanted an application for, I added it to Black Hole.

Black Hole provides the following:
 * A quick and easy way of deleting files. All of the wipe options can be set
   from within Black Hole.
 * It provides wipe features not normally available, such as the ability to
   retain directories.
 * It can be configured to keep a backup copy of any file it deletes, for a
   specified length of time. This is for those of you who delete things by
   accident. I know I do, but then I've got a screw well and truly undone.
   Wibble.
 * All operations are multitasked as much as possible. This means you can get
   on with other things while BlackHole grinds away at your disc.
 * It provides a facility for saving files from desktop applications into
   specified directories.
 * It contains a file find utility. A very nice file find utilty, in fact. If
   quantity of code were any measure of relative importance, Black Hole would
   be a file-finder with an add-on wastebin. But it wasn't intended like that
   Wibble.
 * It puts a nice sprite on your iconbar which spins round or indulges in
   some other needless but rather fun activity.
 * It contains a bit for disposing of the junk that lots of applications
   leave hanging around in your module area.
 * It allows you to put TinyDirs icons on your icon bar without having to
   run !TinyDirs
 * It contains a configurable screen saver, which uses up no extra memory
   when not running, and for which you can write your own savers in BASIC.
 * Black Hole is fully compatible with Acorn's !Help. For those of you who
   don't want to read any more of this rubbish.

Black Hole has many features. Do not be put off if it appears complicated,
it's actually very simple, and you don't need to understand most of it
anyway. Most of the rest of this Help file is more coherent than it has been
so far. All the explanations are perfectly clear. Any inability to understand
them is purely the fault of the reader and the author accepts no criticisms
of his grammar. She's a very nice old lady. Wibble.

[12]
Actually, the most useful thing it does is to not delete files. Hopefully
you are now confused. Good, I thought so. What I mean is that Black Hole
doesn't actually delete files when you drag them onto Black Hole. What it
does is to move them somewhere else where you can't see them. The place it
moves them to is called the 'Bin Directory'.

It will keep files in the bin directory for ever, but you can tell it to
automatically delete them after a certain number of days.

[34]
As this help is for clever people, I'll explain something else. Black Hole,
like other wastebins, doesn't actually delete files, it just moves them
somwhere else. What sets Black Hole apart is that once it has moved the
files there, it 'ages' them so that they are automatically deleted after a
set number of days.

All wastebin programs need somewhere to store their rubbish. Some wastebin
programs incorporate the rubbish as part of the code. This author prefers to
let users supply their own rubbish. Such user-interactiveness is part of what
makes life worth living. Or something. To store rubbish, Black Hole requires
a directory which is imaginatively called the 'Bin Directory'. Normally this
is the directory !BlakHole2.BlackHole, but may have been changed by the
person who gave you the program. If this is the case, then Black Hole will
probably report an error the first time it is run informing you that the
Bin Directory cannot be found. What it then does is to revert to the default
Bin Directory and save this to disc so that the error does not occur again.
See below for more information about the Bin Directory. If you simply cannot
get the program to run (a very, very unlikely probability) then check that
the application contains all the files described at the end of this file, and
try deleting the files 'Options' and 'SaveOpts'.

                            The Bin Directory
                            =================

A few words about this may be useful. Then again, they may not. But you never
know unless you try.

1) Files copied to the bin directory are placed in a subdirectory called
xxxx_yy_zz where xxxx is the year (eg 1993) ,yy is the month and zz is the
day of the month. Clicking Select over the iconbar icon opens the directory
for today if it exists, otherwise the root bin directory is opened.

2) When copying to the bin directory, Black Hole will go by the fastest
possible route - i.e. it will rename files if possible as this is faster than
copying and then deleting. However, if 'Force' is not set, Black Hole
must first copy and then delete files as Rename ignores the access status
of files. This results in two Filer Action windows appearing one after the
other.

3) Any files or directories placed in the ROOT bin directory which do not
have names of the form "xxxx_yy_zz" will be deleted next time Black Hole
is run.

4) If you have Andrew Hersee's Filer2 and the WimpSprite module, then the
current bin directory will be represented by a picture of a dustbin in the
bin directory filer window. This is utterly pointless, but it gives you
another reason to use Black Hole.

[4]
----------------------------------------------------------------------------
                 Running BlakHole2 from Read-Only media
                 
This version of Black Hole can be run from a read-only medium such as CD-ROM.
In order to do this, edit the !Run file so that it contains the line
Set BlackHole$CDROM Yes
When this is set, Black Hole will assume that it cannot write anything into
its home directory and therefore will make the default bin directory
Wimp$ScrapDir.BlackHole. It will also save all its options files to
!System.BlackHole.

----------------------------------------------------------------------------

[12]
Each time a file is copied into the Bin directory, it is placed in a sub-
directory with the name "XXXX_YY_ZZ", where XXXX is the year, YY is the
month, and ZZ is the day. This separates up your rubbish on a daily basis.

[1234]

You can open the Bin Directory by clicking the left mouse button over the
Black Hole icon on the iconbar. If a subdirectory for today exists, that will
be opened in preference.

                           The Black Hole Menu
                           ===================

If you click the middle mouse button over Black Hole's icon, you'll get a
menu with lots of options.

Info      ==> Leads to a window containing information about the program.

Config..      Opens the Configuration window which allows you to set your
              preferred options for all of Black Hole's features. You can
              also open this window by clicking the right mouse button over
              the Black Hole icon on the iconbar.
              
Contents  ==> Leads to a sub-menu which allows you to perform several
              operations on the contents of the Bin Directory. There is a
              further sub-menu off each of these which allows you to select
              any or all of the sub-directories.
              The options on the first sub-menu are:
              Destroy    : Unconditionally wipes everything. There is a
                           confirmation window before this happens.
              Count      : Counts the contents.
              Info       : Reads the contents of the Bin and displays their
                           names, sizes, and types in a window. Clicking
                           SELECT on a filename in this window will open the
                           parent directory of that file.
              Squash     : This will compress all the files in the bin,
                           thus making them take up less disc space.
                           See the entry 'Squash on Shutdown' below for more
                           information.
              Open       : Will open the bin directory selected from the
                           submenu. Selecting 'All' will open all the 
                           subdirectories.

Wipe Drive==> Leads to a window containing the names of any adfs floppy
              drives fitted, and also the RAM disc, if present. Selecting one
              of these will cause the disc in the selected drive to be wiped
              of all its contents. There is a confirmation window before this
              happens, where clicking on 'No' will abort the operation.
[234]              
              If you want to rename the disc, the new name can be entered
              in the submenu off this menu. Leaving this submenu blank will
              keep the same name for the disc. This menu will also
              recognise Brian Brunswick's MemFS filer if it is present.
[1234]

Auto Saver..  Opens the Auto File Saver window. See the appropriate Help.

Find File ... Opens the File Finder window, which can be used to search
              a directory structure for all files of a particular name
              or type. See below for a fuller explanation.

[12]
The next three options (Module Kill, Run File, and Add Tiny Dir) are too
advanced for your poor brain to cope with. Try a higher tecnical help level
if you want to know more.

[34]
Module Kill > Allows you to kill modules by name or by pre-defined lists.
              This is explained more fully below.
              
Run File  ==> Leads to a submenu containing the names of all the files on
              Run$Path. Clicking on one of these names will run the file.
              More information is supplied later.

Add Tiny Dir> Is fairly self-explanatory if you know what Tiny Dirs are. If
              you don't I suggest you read the RISC OS user guide thingy.
              Look under Tiny Dirs or !TinyDirs or something like that. This
              menu item has a submenu, the function of which is readily
              apparrent if you try and use it. Note that this menu option
              will be greyed out if you have Unplugged the Pinboard module.

[1234]
Quit          Quits the Black Hole

[34]
                         Menu Options in More Detail
                         ===========================
                         
This section describes the menu options which are not covered more fully
elsewhere.

Module Kill.
============

One of the things I find annoying about many applications (Computer Concepts
please note) is that when you quit them they leave all their junk behind in
the RMA. My RISC OS 3 BJ10 turbodriver leaves 8 modules behind. This
obviously uses up a fair proportion of the RMA. This is what Module Kill is
all about. The submenu has three entries. These may be the only entries, or
there may be some more below a dotted line. Whatever. The third entry is
'Name'; Moving  right off this gives you a list of modules currently in the
RMA. Selecting one will cause Black Hole to attempt to kill it.
The second entry is 'Minimize'. When you select this, Black Hole will attempt
to reduce the size of the module area to a minimum. Usually it fails because
the MEMC isn't violent enough. The first option is 'Open Dir', and this is
where the fun starts.

Selecting 'Open Dir' opens a directory. Surprised? There may be a few files
in this directory, or there may not be. It doesn't matter. What is this
directory for? Right. What you need to do is to find an application which
leaves some modules behind when you quit it. Black Hole will give you a 
list of modules on the 'Name' submenu off the Module Kill menu. Note down
the name of the last module in this list. Now run then quit your application 
and look again at the module list. If the app. has left any modules behind
they will be tacked on the bottom of the list.

Now create a text file (using Edit, say) containing a list of these module
names, one module per line. Save this file, in the directory you opened from
the menu, with a meaningful name. Get the Module Kill menu up again. Your
file will now be on the menu under the dottedline. Selecting the entry for
your file will cause Black Hole to attempt to Kill all the modules listed in
that file, then to minimize the RMA. It is usually successful at the first
bit, but the second bit often causes it problems. Don't worry, it won't crash(Says he confidently).

N.B. It is often a good idea to put the modules in the list in Reverse order
to the order they appear in the list. It just seems to work better that way.

The dangerous bit is if you use Module Kill while the relevant app. is still
running. My advice is 'Don't - It's not fun.'

Run File.
=========

Something else that somebody somewhere might have a use for. When you run it,
BlackHole2 examines all the files on Run$Path (which is usually just the
Library directory) and builds a nice menu up out of them. This menu is
available as a submenu off 'Run File'. Clicking on a filename in this menu
will run the file.
This is primarily intended for those of you who use those old-fashioned unix-
style command line utilities. You can enter parameters to be placed after the
filename in the writable menu off each entry (max. 256 characters).
Thus if 'Squash' is in your library (as it should be if you're doing BlakHole
properly), then it will appear on the menu. To enter the command 
 'Squash adfs::4.$.Womble'
simply enter 'adfs::4.$.Womble' in the writable menu off 'Squash', and click
SELECT or press RETURN.

Due to the command line nature of most of the files I intend people to run
from here, BlakHole2 will attempt to run the program in a TaskWindow. In
other words, you need !Edit or !Zap. Some files refuse to run in TaskWindows,so selecting them while holding down 'Alt' will run them normally. If it
crashes, please don't shout at me. If a Task Window server cannot be found,
Black Hole will take alternative action.

Because of the appallingly long time it can take to build this menu, it is
done once only, at the start. However, help is at hand in the form of the
first option - 'Rebuild...'. I'll leave it up to your great intellects to
figure out what this one does.

[234]
Notes: 
======

1) Rather than using Squash, which is rather slow, you may like to compress
   your Retained Copies by another method. This is most easily done if you
   own Computer Concept's Compression. You can simply make the Bin Directory
   a CFS directory. Provided CFS is loaded before Black Hole on bootup,
   everything will be OK. This has the added advantage that files are
   compressed as they are added to the bin.
   For example, you could make the bin directory 
     CFS#adfs::IDEDisc4.$.!BlakHole2.BlackHole.
   You can probably do this with SparkFS as well.

2) Dragging the contents of the Bin directory to the iconbar icon WILL delete
   them if force is off, but will not if force is on. This is because force
   MOVES files, but force off copies then deletes. If Retain Copies is off,
   or Ctrl is pressed, then they will be deleted whatever.

3) Black Hole treats DOS partitions as normal directories for all purposes.
   If a DOS partition is deleted with 'Retain Copies' set, then the files are
   retained but in a directory with the same name as the partition, not as
   a partition. This probably applies to archives if SparkFS is running,
   but I haven't tried it so don't quote me.

4) If you want to customize Black Hole to use fonts other than the defaults,
   then load the file 'Messages' into a text editor (eg !Edit) and change the
   relevant lines in there. It's self-explanatory and very easy really,
   honest. Note that the fonts listed in this file will only be applied if
   the 'Menu Font' and/or 'Clock Font' icon in the config window is on.

5) Observant people (those with one or more eyes and a functioning brain) may
   notice that the file finder searches backwards down a group of
   directories, i.e. if your root directory has five subdirectories such as
   !Boot, !Fonts, !System, !Scrap, and Apps, the file finder will search
   them in reverse order. This is simply because of the way it works and
   I've not bothered to change it because it means that almost everything
   gets searched before !Fonts, which really doesn't need searching anyway,
   and so the search can be manually aborted at this point.

Brief Explanation of Contents of !BlakHole2.
============================================

!Boot and !Run are the usual stuff.

!Help runs the Help program.

!RunImage is the program.

!Sprites and !Sprites22 are the filer sprites.

BlackHole is the default bin directory.

HoleMod is the BlackHole module.

icons contains the sprites used in the windows.

Messages contains the Help Text and other such nonsense.

ModuleKill contains the files used in the 'Module Kill' section.

Sprites contains the sprite files for the animation of the iconbar icon. By
default these are BlakHole, BlakHole22, Recycle, Burn, Mouth, and Shredder.

Temp is a directory used when directory structure needs to be retained.

Templates are...... the templates!!

!BHHelp is the Master Help program. This MUST NOT be moved from the
!BlakHole2 directory

!BlackOut is the BlackOut Screen saver. This MUST NOT be moved from the
!BlakHole2 directory.

!BlkOutCfg is the configuration program for BlackOut. This too, must remain
in the !BlakHole2 directory.

!Ukelele is the application finder.

Options is where the Config. options are saved.

Saveopts is the options for the Auto Saver. You can alter this using Edit if
you like, just save a sample file to find out the format.

If these last two files are not present, Black Hole will use its own defaults
for all the options.

[1234]
Random Ramblings
================

This program is far from perfect. The reasons for this are many and varied
and the word 'incompetence' appears in them frequently. A large part of it
is because I learnt to program RISC OS by staring vacantly at other people's
programs until the sugar of understanding began to crystallise in the
syrup of my brain. (Sorry, too much psychedelic music.)
By the way, I can strongly recommend the method of programming I use:
1) Decide what it is you want to do.
2) Find a program that already does it.
3) 'Adapt' the code in that program.
4) Have a coffee.
This works very successfully and probably explains why I've got three
apparrently identical procedures, each of which is absolutely crucial to the
program. Ho hum.
Please note, however, that this is not an admission of plagiarism. 
Other people's programs are a great source of PRM-type information, and are
usually far more easily understandable than Acorn literature.

The next bit is a load of boring pseudo-legal crap which I put
in because everybody else does, so it seemed like a good idea.
